This reference is generated from the Topsort openapi specification and includes quite a few operations.
However, only two are required for a typical integration.
Provide your catalog via a product feed.
(Have vendors create campaigns).
Run auctions via the API or using our clients.
The details will depend on your marketplace and needs. A selection of examples is available here.
Use one of the analytics libraries to report events.
Typical integrations will use these APIs:
For advanced integrations you might want to look at:
To minimize the impact of auctions on your app’s performance, there is no redirect from URLs with a trailing slash (/
). This is to avoid an extra round trip before auction winners are returned.
For example, when you want to run an auction, use /v2/auctions
, not /v2/auctions/
.
Using an URL with a trailing slash will result in a 404 Not Found
error.
You can monitor and check API Status here.
Topsort enforces rate limits on some of the endpoints to ensure that the quality of service is maintained for all users. The rate limits are different for the production and sandbox environments and are as follows:
Environment | Endpoint | Rate Limit |
---|---|---|
Sandbox | Catalog API | 4 rps |
Sandbox | Other Advanced APIs | 5 requests every 2 seconds |
Sandbox | Auctions and Events | No rate limit |
Production | Catalog API | 10 rps |
Production | Other Advanced APIs | 45 requests every 2 seconds |
Production | Auctions and Events | No rate limit |
Use these headers to navigate rate limits and when you can make another request:
X-RateLimit-Limit
- total number of requests allowed for the time periodX-RateLimit-Remaining
- remaining number of requests for the time periodX-RateLimit-Reset
- when you can make another requestWhen you exceed the rate limit, you will receive a 429 Too Many Requests
response. To handle this, you can implement a retry mechanism with an exponential backoff strategy. This will help you to avoid hitting the rate limit again.
Here is an example of how you can implement this in Typescript:
The OpenAPI specification is available as a JSON file here.